


SOX(1)							   SOX(1)


NNAAMMEE
       sox - SOund eXchange : universal sound sample translator

SSYYNNOOPPSSIISS
       ssooxx _i_n_f_i_l_e _o_u_t_f_i_l_e
       ssooxx _i_n_f_i_l_e _o_u_t_f_i_l_e [[ _e_f_f_e_c_t [[ _e_f_f_e_c_t _o_p_t_i_o_n_s _._._. ]] ]]
       ssooxx _i_n_f_i_l_e --ee _e_f_f_e_c_t [[ _e_f_f_e_c_t _o_p_t_i_o_n_s _._._. ]]
       ssooxx  [ _g_e_n_e_r_a_l _o_p_t_i_o_n_s  ]] [[ _f_o_r_m_a_t _o_p_t_i_o_n_s  ]] _i_f_i_l_e [[ _f_o_r_-
       _m_a_t _o_p_t_i_o_n_s  ]] _o_f_i_l_e [[ _e_f_f_e_c_t [ _e_f_f_e_c_t _o_p_t_i_o_n_s _._._. ]] ]]
       _G_e_n_e_r_a_l _o_p_t_i_o_n_s_: [[ --hh ]] [[ --VV ]] [[ --vv _v_o_l_u_m_e ]]
       _F_o_r_m_a_t _o_p_t_i_o_n_s_: [[ --tt _f_i_l_e_t_y_p_e ]] [[ --rr _r_a_t_e ]] [[  --ss//--uu//--UU//--AA
       ]] [[ --bb//--ww//--ll//--ff//--dd//--DD ]] [[ --cc _c_h_a_n_n_e_l_s ]] [[ --xx ]]
       _E_f_f_e_c_t_s_:
	    ccooppyy
	    rraattee
	    aavvgg [[ _-_l || _-_r ]]
	    rreessaammppllee
	    mmaasskk
	    ssttaatt
	    eecchhoo _d_e_l_a_y _v_o_l_u_m_e [[ _d_e_l_a_y _v_o_l_u_m_e _._._. ]]
	    vviibbrroo _s_p_e_e_d [[ _d_e_p_t_h ]]
	    lloowwpp _c_e_n_t_e_r
	    hhiigghhpp _c_e_n_t_e_r
	    bbaanndd [[ _-_n ]] _c_e_n_t_e_r [[ _w_i_d_t_h ]]

DDEESSCCRRIIPPTTIIOONN
       _S_o_x  translates	sound  files  from one format to another,
       possibly doing a sound effect.

OOPPTTIIOONNSS
       The option syntax is a little grotty, but in essence:
	    sox file.au file.voc
       translates a sound sample in SUN Sparc .AU format  into	a
       SoundBlaster .VOC file, while
	    sox -v 0.5 file.au -rate 12000 file.voc rate
       does  the  same	format	translation  but  also lowers the
       amplitude by 1/2 and changes the sampling rate  from  8000
       hertz to 12000 hertz via the rraattee _s_o_u_n_d _e_f_f_e_c_t loop.

       File type options:

       --tt _f_i_l_e_t_y_p_e
		 gives the type of the sound sample file.

       --rr _r_a_t_e	 Give sample rate in Hertz of file.

       --ss//--uu//--UU//--AA
		 The  sample  data  is signed linear (2's comple-
		 ment), unsigned linear, U-law (logarithmic),  or
		 A-law	(logarithmic).	 U-law	and A-law are the
		 U.S. and international standards for logarithmic
		 telephone sound compression.





			 February 23 1997			1





SOX(1)							   SOX(1)


       --bb//--ww//--ll//--ff//--dd//--DD
		 The  sample  data  is	in  bytes,  16-bit words,
		 32-bit longwords, 32-bit floats,  64-bit  double
		 floats,  or 80-bit IEEE floats.  Floats and dou-
		 ble floats are in native machine format.

       --xx	 The sample data is in XINU format; that  is,  it
		 comes	from  a	 machine  with	the opposite word
		 order than yours and must be  swapped	according
		 to  the  word-size given above.  Only 16-bit and
		 32-bit integer data may  be  swapped.	 Machine-
		 format	 floating-point	 data  is  not	portable.
		 IEEE floats are a fixed, portable format. ???

       --cc _c_h_a_n_n_e_l_s
		 The number of sound channels in the  data  file.
		 This  may  be	1,  2, or 4; for mono, stereo, or
		 quad sound data.

       General options:

       --ee	 after the input file allows you to avoid  giving
		 an output file and just name an effect.  This is
		 only useful with the ssttaatt effect.

       --vv _v_o_l_u_m_e Change amplitude (floating point); less than 1.0
		 decreases, greater than 1.0 increases.	 Note: we
		 perceive volume logarithmically,  not	linearly.
		 Note: see the ssttaatt effect.

       --hh	 Print version number and usage information.

       --VV	 Print	a description of processing phases.  Use-
		 ful for figuring out exactly how _s_o_x is mangling
		 your sound samples.

       The  input and output files may be standard input and out-
       put.  This is specified by '-'.	The --tt _t_y_p_e  option  must
       be  given  in this case, else _s_o_x will not know the format
       of   the	  given	  file.	   The	 --tt,,   --rr,,   --ss//--uu//--UU//--AA,,
       --bb//--ww//--ll//--ff//--dd//--DD  and  --xx options refer to the input data
       when given before the input file name.  After, they  refer
       to the output data.

       If  you don't give an output file name, _s_o_x will just read
       the input file.	This is useful for validating  structured
       file  formats; the ssttaatt effect may also be used via the --ee
       option.

FFIILLEE TTYYPPEESS
       _S_o_x needs to know the formats  of  the  input  and  output
       files.	File  formats  which have headers are checked, if
       that header doesn't seem right, the program exits with  an
       appropriate  message.   Currently,  raw (no header) binary



			 February 23 1997			2





SOX(1)							   SOX(1)


       and textual data, IRCAM Sound Files, Sound Blaster,  SPARC
       .AU  (w/header),	 Mac  HCOM,  PC/DOS  .SOU,  Sndtool,  and
       Sounder, NeXT .SND, Windows  3.0	 RIFF/WAV,  Turtle  Beach
       .SMP,  CD-R, Psion .WVE, CVSD, and Apple/SGI AIFF and 8SVX
       formats are supported.


       ..88ssvvxx	 Amiga 8SVX musical instrument	description  for-
		 mat.

       ..aaiiffff	 AIFF  files  used  on	Apple  IIc/IIgs	 and SGI.
		 Note: the AIFF format	supports  only	one  SSND
		 chunk.	  It  does  not	 support  multiple  sound
		 chunks, or the 8SVX musical instrument	 descrip-
		 tion format.  AIFF files are multimedia archives
		 and and can  have  multiple  audio  and  picture
		 chunks.   You	may  need  a separate archiver to
		 work with them.

       ..aauu	 SUN Microsystems AU files.  There are apparently
		 many  types  of  .au files; DEC has invented its
		 own with  a  different	 magic	number	and  word
		 order.	 The .au handler can read these files but
		 will not write them.  Some .au files have  valid
		 AU  headers  and  some	 do  not.  The latter are
		 probably original SUN	u-law  8000  hz	 samples.
		 These can be dealt with using the

       ..ccddrr	 CD-R
		 CD-R  files  are used in mastering music Compact
		 Disks.	 The file format is, as you might expect,
		 raw  stereo raw unsigned samples at 44khz.  But,
		 there's some blocking/padding oddity in the for-
		 mat, so it needs its own handler.

       ..ddaatt	 Text Data files
		 These	files contain a textual representation of
		 the sample data.   There  is  one  line  at  the
		 beginning that contains the sample rate.  Subse-
		 quent lines contain two numeric data items:  the
		 time  since  the beginning of the sample and the
		 sample value.	Values are normalized so that the
		 maximum  and  minimum	are 1.00 and -1.00.  This
		 file format can be used to create data files for
		 external programs such as FFT analyzers or graph
		 routines.  SOX can also convert a file	 in  this
		 format	 back into one of the other file formats.

       ..hhccoomm	 Macintosh HCOM files.	 These	are  (apparently)
		 Mac FSSD files with some variant of Huffman com-
		 pression.  The Macintosh has wacky file  formats
		 and  this format handler apparently doesn't han-
		 dle all the ones it should.  Mac users will need
		 your  usual  arsenal  of file converters to deal



			 February 23 1997			3





SOX(1)							   SOX(1)


		 with an HCOM file under Unix or DOS.

       ..mmaauudd	 An Amiga format
		 An IFF-conform sound file type, registered by MS
		 MacroSystem  Computer GmbH, published along with
		 the "Toccata" sound-card on the  Amiga.   Allows
		 8bit  linear, 16bit linear, A-Law, u-law in mono
		 and stereo.

       ..rraaww	 Raw files (no header).
		 The sample rate, size	(byte,	word,  etc),  and
		 style	(signed,  unsigned,  etc.)  of the sample
		 file must be  given.	The  number  of	 channels
		 defaults to 1.

       ..uubb,, ..ssbb,, ..uuww,, ..ssww,, ..uull
		 These	are  several  suffices	which  serve as a
		 shorthand for raw files with a	 given	size  and
		 style.	  Thus, uubb,, ssbb,, uuww,, ssww,, and uull correspond
		 to "unsigned  byte",  "signed	byte",	"unsigned
		 word",	 "signed  word",  and "ulaw" (byte).  The
		 sample rate defaults to 8000 hz if  not  explic-
		 itly set, and the number of channels (as always)
		 defaults to 1.	 There are lots of Sparc  samples
		 floating  around  in u-law format with no header
		 and fixed at a sample rate of 8000 hz.	 (Certain
		 sound management software cheerfully ignores the
		 headers.)  Similarly, most Mac sound  files  are
		 in  unsigned  byte  format with a sample rate of
		 11025 or 22050 hz.

       ..ssff	 IRCAM Sound Files.  SoundFiles are used by  aca-
		 demic music software such as the CSound package,
		 and the MixView sound sample editor.

       ..ssmmpp	 Turtle Beach SampleVision files.
		 SMP files are for use with  the  PC-DOS  package
		 SampleVision  by  Turtle  Beach  Softworks. This
		 package is for	 communication	to  several  MIDI
		 samplers.  All sample rates are supported by the
		 package, although not all are supported  by  the
		 samplers  themselves.	Currently loop points are
		 ignored.

       ..vvoocc	 Sound Blaster VOC files.
		 VOC files are	multi-part  and	 contain  silence
		 parts,	 looping,  and different sample rates for
		 different chunks.  On input, the  silence  parts
		 are  filled  out, loops are rejected, and sample
		 data  with  a	new  sample  rate  is	rejected.
		 Silence  with	a different sample rate is gener-
		 ated appropriately.  On output, silence  is  not
		 detected, nor are impossible sample rates.




			 February 23 1997			4





SOX(1)							   SOX(1)


       ..vvoocc	 Sound Blaster VOC files.
		 VOC  files  are  multi-part  and contain silence
		 parts, looping, and different sample  rates  for
		 different  chunks.   On input, the silence parts
		 are filled out, loops are rejected,  and  sample
		 data	with  a	 new  sample  rate  is	rejected.
		 Silence with a different sample rate  is  gener-
		 ated  appropriately.	On output, silence is not
		 detected, nor are impossible sample rates.

       ..wwaavv	 Windows 3.0 .WAV RIFF files.
		 These appear to be very similar  to  IFF  files,
		 but  not  the	same.	They are the native sound
		 file format of Windows 3.0.  (Obviously, Windows
		 3.0  was  of  such  incredible importance to the
		 computer industry that it just had to	have  its
		 own  sound  file  format.)   Normally ..wwaavv files
		 have all formatting information in  their  head-
		 ers, and so do not need any format options spec-
		 ified for an input file. If any are,  they  will
		 overide  the file header, and you will be warned
		 to this effect.  You had better  know	what  you
		 are  doing!  Output  format options will cause a
		 format conversion, and	 the  ..wwaavv  will  written
		 appropriately.	  Note	that  it  is  possible to
		 write data of a type that cannot be specified by
		 the ..wwaavv header, and you will be warned that you
		 a writing a bad file !

       ..wwvvee	 Psion 8-bit alaw
		 These are 8-bit a-law 8khz sound files	 used  on
		 the Psion palmtop portable computer.

       ..aauuttoo	 This  is  a  ``meta-type'': specifying this type
		 for an input file triggers some code that  tries
		 to  guess  the	 real  type  by looking for magic
		 words in the  header.	 If  the  type	can't  be
		 guessed,  the	program	 exits with an error mes-
		 sage.	The input must be a  plain  file,  not	a
		 pipe.	This type can't be used for output files.

EEFFFFEECCTTSS
       Only one effect from the palette may be applied to a sound
       sample.	 To do multiple effects you'll need to run _s_o_x in
       a pipeline.

       copy			     Copy the input file  to  the
				     output  file.   This  is the
				     default effect if both files
				     have the same sampling rate,
				     or the rates are "close".

       rate			     Translate	 input	 sampling
				     rate to output sampling rate



			 February 23 1997			5





SOX(1)							   SOX(1)


				     via linear interpolation  to
				     the Least Common Multiple of
				     the  two	sampling   rates.
				     This  is  the default effect
				     if the two files  have  dif-
				     ferent sampling rates.  This
				     is fast but noisy: the spec-
				     trum  of  the original sound
				     will be shifted upwards  and
				     duplicated	 faintly when up-
				     translating by  a	multiple.
				     Lerp-ing  is  acceptable for
				     cheap 8-bit sound	hardware,
				     but for CD-quality sound you
				     should instead use:

       resample [ _r_o_l_l_o_f_f [ _b_e_t_a ] ] Translate	 input	 sampling
				     rate to output sampling rate
				     via simulated analog filtra-
				     tion.   This  method is slow
				     and uses lots  of	RAM,  but
				     gives  much  better  results
				     then rraattee..

       mask			     Add "masking noise" to  sig-
				     nal.   This  effect deliber-
				     ately adds white noise to	a
				     sound in order to mask quan-
				     tization effects, created by
				     the  process  of  playing	a
				     sound digitally.	It  tends
				     to	 mask buzzing voices, for
				     example.  It adds 1/2 bit of
				     noise  to	the sound file at
				     the output bit depth.

       avg [ _-_l | _-_r ]		     Reduce the number	of  chan-
				     nels  by  averaging the sam-
				     ples, or duplicate	 channels
				     to	 increase  the	number of
				     channels.	 Valid	 combina-
				     tions  are 1 - 2, 1 - 4, 2 -
				     4, 4 - 2, 4 - 1, 2 - 1.  The
				     _-_l	 or  _-_r	 option	 averages
				     from  just	 left  or   right
				     channels/duplicates  to just
				     the left or right	channels.

       stat			     Do	 a  statistical	 check on
				     the input	file,  and  print
				     results   on   the	 standard
				     error file.  ssttaatt	may  copy
				     the   file	  untouched  from
				     input  to	output,	 if   you



			 February 23 1997			6





SOX(1)							   SOX(1)


				     select  an output file.  The
				     "Volume  Adjustment:"  field
				     in	 the statistics gives you
				     the argument to the --vv  _n_u_m_-
				     _b_e_r which will make the sam-
				     ple as loud as possible.

       echo [ _d_e_l_a_y _v_o_l_u_m_e _._._.	]]    Add echoing to a sound  sam-
				     ple.  Each delay/volume pair
				     gives the delay  in  seconds
				     and  the volume (relative to
				     1.0) of that echo.	  If  the
				     volumes  add up to more than
				     1.0,  the	sound  will  melt
				     down instead of fading away.

       vibro _s_p_e_e_d  [[ _d_e_p_t_h ]]	     Add the world-famous  Fender
				     Vibro-Champ  sound effect to
				     a sound sample  by	 using	a
				     sine   wave  as  the  volume
				     knob.  SSppeeeedd gives the Hertz
				     value  of	the  wave.   This
				     must  be  under  30.   DDeepptthh
				     gives  the amount the volume
				     is	 cut  into  by	the  sine
				     wave, ranging 0.0 to 1.0 and
				     defaulting to 0.5.

       lowp _c_e_n_t_e_r		     Apply  a  low-pass	  filter.
				     The frequency response drops
				     logarithmically with  _c_e_n_t_e_r
				     frequency	in  the middle of
				     the drop.	The slope of  the
				     filter is quite gentle.

       highp _c_e_n_t_e_r		     Apply  a  high-pass  filter.
				     The frequency response drops
				     logarithmically  with _c_e_n_t_e_r
				     frequency in the  middle  of
				     the  drop.	 The slope of the
				     filter is quite gentle.

       band [[ _-_n ]] _c_e_n_t_e_r [[ _w_i_d_t_h ]]  Apply  a  band-pass  filter.
				     The frequency response drops
				     logarithmically  around  the
				     _c_e_n_t_e_r frequency.	The _w_i_d_t_h
				     gives the slope of the drop.
				     The  frequencies at _c_e_n_t_e_r _+
				     _w_i_d_t_h  and	 _c_e_n_t_e_r	 _-  _w_i_d_t_h
				     will be half of their origi-
				     nal    amplitudes.	     BBaanndd
				     defaults  to a mode oriented
				     to	 pitched  signals,   i.e.
				     voice,	 singing,      or



			 February 23 1997			7





SOX(1)							   SOX(1)


				     instrumental music.  The  _-_n
				     (for  noise) option uses the
				     alternate	 mode	for   un-
				     pitched	signals.     BBaanndd
				     introduces	 noise	 in   the
				     shape  of	the  filter, i.e.
				     peaking at the  _c_e_n_t_e_r  fre-
				     quency  and  settling around
				     it.

       cut _l_o_o_p_n_u_m_b_e_r		     Extract loop #N from a  sam-
				     ple.

       map			     Display a list of loops in a
				     sample,  and   miscellaneous
				     loop info.

       pick			     Select  the  left	or  right
				     channel of a stereo  sample,
				     or one of four channels in a
				     quadrophonic sample.

       split			     Turn a mono  sample  into	a
				     stereo sample by copying the
				     input channel  to	the  left
				     and right channels.

       _S_o_x  enforces certain effects.  If the two files have dif-
       ferent sampling rates, the requested effect must be one of
       ccooppyy,,  or rraattee,, If the two files have different numbers of
       channels, the aavvgg effect must be requested.

       reverse			     Reverse  the  sound   sample
				     completely.    Included  for
				     finding Satanic subliminals.

BBUUGGSS
       The  syntax  is horrific.  It's very tempting to include a
       default system that allows an effect name as  the  program
       name  and just pipes a sound sample from standard input to
       standard output, but the problem of inputting  the  sample
       rates makes this unworkable.

FFIILLEESS
SSEEEE AALLSSOO
NNOOTTIICCEESS
       The   echoplex  effect  is:  Copyright  (C)  1989  by  Jef
       Poskanzer.

       Permission to use, copy, modify, and distribute this soft-
       ware and its documentation for any purpose and without fee
       is hereby  granted,  provided  that  the	 above	copyright
       notice  appear  in all copies and that both that copyright
       notice and this permission  notice  appear  in  supporting



			 February 23 1997			8





SOX(1)							   SOX(1)


       documentation.	This software is provided "as is" without
       express or implied warranty.























































			 February 23 1997			9


